import { PackageManagerTabs } from '@theme';
import Preparation from '../../shared/preparation.md'

# 使用 Tailwind CSS

Tailwind CSS 是一个以 Utility Class 为基础的 CSS 框架和设计系统，可以快速地为组件添加常用样式，同时支持主题样式的灵活扩展。

您可以通过 PostCSS 插件来在 EMP 中接入 Tailwind CSS。

## 安装 

EMP内置支持了 `postcss` 和 `autoprefixer` ，你只需要安装 `tailwindcss` ，无须安装其他npm包，调用命令安装：

<PackageManagerTabs command="add tailwindcss -D" />

安装完毕后，使用 Tailwind CSS 所需的依赖安装完毕🎉！

## 配置
在使用 Tailwind CSS 之前，您可以还需要配置引用 Tailwind CSS 到您的项目中：
+ 首先，我们先在项目根目录创建一个 `emp-config.js`
```js title="emp-config.js"
import {defineConfig} from '@empjs/cli'
import pluginPostcss from '@empjs/plugin-postcss'
import pluginReact from '@empjs/plugin-react'
export default defineConfig(store => {
  return {
    plugins: [pluginReact(), pluginPostcss()],
  }
})

```

+ 再次创建 `postcss.config.cjs` 用于将 Tailwind CSS 注册为 PostCSS 插件，然后在文件中添加如下内容：

```cjs title="postcss.config.cjs"
module.exports = {
  plugins: {
    tailwindcss: {},
  },
};
```

:::info 💡 TIP
EMP内置了 autoprefixer ，因此你只需要注册 tailwindcss 插件。在这里，您也可以通过 tools.postcss注册 tailwindcss 插件。
:::

+ 最后，我们创建一个`tailwind.config.js`文件用于配置Tailwind CSS，并添加如下内容至文件中：

```js title="tailwind.config.js"
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

:::warning ⚠️ 注意
上述配置仅供参考，具体配置请以实际项目需求为准，例如 vue 项目需要添加 vue 文件，非 TypeScript 项目不需要包含 ts 和 tsx 文件。
:::

## 引入样式

前面我们已经配置好了 Tailwind CSS ，接下来，我们需要在入口样式文件进行引入，常见的引入情况有 css、scss、less，具体内容如下：

- **css：**
  ``` css title="main.css"
  @tailwind base;
  @tailwind components;
  @tailwind utilities;
  ```
- **scss：**
  ``` scss title="main.scss"
  @import "tailwindcss/base";
  @import "tailwindcss/components";
  @import "tailwindcss/utilities";
  ```
- **less：**
  ``` less title="main.less"
  @import "tailwindcss/base";
  @import "tailwindcss/components";
  @import "tailwindcss/utilities";
  ```

:::details 📢 说明
根据需求不同，您可以选择性地导入 Tailwind CSS 提供的 CSS 样式。请参考 [@tailwind 文档](https://tailwindcss.com/docs/functions-and-directives#tailwind) 来了解 @tailwind 指令的详细用法。
:::

## 测试

至此，您已经完成EMP接入 Tailwind CSS 的全部步骤🎊，您可以添加如下代码来测试是否成功：

```html
<h1 class="text-5xl font-bold underline">Hello world!</h1>
```

更多用法请参考 [Tailwind CSS 文档](https://tailwindcss.com/)。

## 示例

对于Tailwind CSS，我们准备了三个框架下的最简示例仅供参考。三个最简示例在 `emp` 仓库下，请按如下命令安装：

```bash
git clone https://github.com/empjs/emp
```

:::danger 🚨 可能遇到的错误
如果您无法拉取项目至本地，请检查您的网络环境或代理设置是否可以访问github，如果仍不能解决，请联系我们。
:::

在拉取完成代码后，我们进入代码的根目录，安装项目依赖，推荐使用`PNPM`进行安装：

<PackageManagerTabs command="install" />

安装完依赖后，运行 Tailwind CSS 示例项目的前期准备就完成了🎉。

:::warning ⚠️ 注意
在运行示例项目之前，请确保您已经完成了前期准备，并当前目录处于`emp`仓库的根目录下。
:::

### Vue2版本

Vue2 版本的 Tailwind CSS 示例项目在 `projects/tailwind-vue2` 目录下，我们先进入项目的根目录：

```bash
cd projects/tailwind-vue2
```

然后运行构建项目：
<PackageManagerTabs command="dev" />

最后，您可以在 `http://localhost:9002/` 查看示例效果👀。


### Vue3版本

Vue3 版本的 Tailwind CSS 示例项目在 `projects/tailwind-vue3` 目录下，我们先进入项目的根目录：

```bash
cd projects/tailwind-vue3
```

然后运行构建项目：
<PackageManagerTabs command="dev" />

最后，您可以在 `http://localhost:9001/` 查看示例效果👀。


### React版本

React 版本的 Tailwind CSS 示例项目在 `projects/tailwind-react` 目录下，我们先进入项目的根目录：

```bash
cd projects/tailwind-react
```

然后运行构建项目：
<PackageManagerTabs command="dev" />

最后，您可以在 `http://localhost:8000/` 查看示例效果👀。


## VS Code 插件

Tailwind CSS 提供了 [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) 插件，用于在 VS Code 中自动补全 Tailwind CSS 的 class names、CSS functions 和 directives。

您可以在 VS Code 中安装该插件，即可开启自动补全功能✅。

## 构建优化

在使用 Tailwind CSS 时，如果没有正确地配置 `tailwind.config.js` 中的 `content` 字段，可能会导致构建性能和热更新性能下降。这是因为 Tailwind CSS 内部会基于 `content` 定义的 glob 来匹配文件，扫描的文件数量越多，产生的性能开销越大😣。

因此，我们建议精确地指定需要扫描的路径，以避免不必要的性能开销。例如，仅包括项目源码中实际包含 Tailwind 类名的 HTML 或 JS 文件，避免包含不相关的文件或目录，尤其是 `node_modules` 目录。

下面是一个扫描 `node_modules` 的错误示例❌：

```js title="tailwind.config.js"
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{html,js,ts,jsx,tsx}',
    // 扫描大量文件，导致性能下降
    './node_modules/**/*.js',
  ],
};
```